Chrome 插件开发入门教程
1. 介绍
Chrome 插件（也称为扩展程序）是用来扩展和增强 Google Chrome 浏览器功能的小程序。它们允许用户定制和扩展浏览器的功能，为用户提供更丰富、更高效的浏览体验。无论是广告拦截、密码管理、页面翻译，还是开发者工具，Chrome 插件都能满足各种需求。通过创建 Chrome 插件，开发者可以在用户浏览网页时增加额外的功能和体验，提高用户的工作效率和浏览体验。
Manifest V3 (MV3) 是 Chrome 插件的新版本，相较于之前的 Manifest V2 (MV2)，MV3 提供了更高的安全性和性能，同时对隐私保护也做了更严格的规范。MV3 的主要改进包括：
更新 Manifest 配置： manifest.json版本必须为V3，同时文件格式也发生了改变。迁移到 Service Worker： Service Worker 替换 V2 中的后台或事件页面，以确保后台代码远离主线程，从而降低性能。此更改还需要将 DOM、窗口和某些扩展 API 调用移入屏幕外的文档中。 更新 API 调用： 某些 API 调用需要替换为更现代的等效项。 替换阻止网络请求监听器： 在 Manifest V2 中屏蔽或修改网络请求可能会显著降低性能，并导致需要过多访问敏感用户数据。借助 Declarative Net Request API，扩展程序可以使用较少的权限来屏蔽或修改 Web 内容，而不会降低性能。 提高扩展程序安全性： Manifest V3 通过多种方式提高扩展程序的安全性。除了增强的内容安全策略之外，不再支持远程托管代码和任意字符串的执行。
本文将详细介绍如何从零开始开发一个简单的 Chrome 插件，包括项目结构、配置文件、脚本编写、加载调试和发布等各个环节。通过学习这个教程，你将掌握 Chrome 插件开发的基础知识，并能创建出符合 MV3 规范的插件。
2. 项目结构
我们首先创建一个基础的项目结构，这将包含开发 Chrome 插件所有必需的文件和目录。
创建项目文件夹
首先，创建一个新的文件夹来存放插件的所有文件，我们将这个文件夹命名为 my-chrome-extension。
mkdir my-chrome-extension
cd my-chrome-extension
项目文件和目录结构
在 my-chrome-extension 文件夹中创建以下文件和目录。这些文件将包含插件的配置、脚本、HTML 和其他资源：
my-chrome-extension/
├── manifest.json. ---------------------- chrome 插件配置文件
├── background.js ---------------------- service work
├── content.js ---------------------- 注入脚本
├── popup.html ---------------------- 插件弹框页面
├── popup.js ---------------------- 插件弹框 js
└── images/ ---------------------- 插件图标
├── icon-16.png
├── icon-48.png
└── icon-128.png
每个文件和文件夹的作用如下：
| 文件/文件夹名 | 描述 |
|---|---|
manifest.json | 插件的配置文件，包含插件的基本信息、权限和其他元数据。 |
background.js | 后台脚本，处理插件的后台逻辑，可以在浏览器后台长时间运行。 |
content.js | 内容脚本，可以访问和修改当前网页的 DOM。 |
popup.html | 插件弹窗的 HTML 文件，定义了插件插件弹窗的结构和样式。 |
popup.js | 处理插件弹窗中的交互逻辑。 |
images/ | 存放插件的图标文件，包括 16x16、48x48 和 128x128 尺寸的图标。 |
示例项目结构
以下是项目结构的示例文件内容，帮助你快速入门：
manifest.json
{
"manifest_version": 3,
"name": "My Chrome Extension",
"version": "1.0",
"description": "一个简单的 Chrome 入门插件示例",
"action": {
"default_popup": "popup.html"
},
"background": {
"service_worker": "background.js"
},
"permissions": ["activeTab", "scripting"],
"content_scripts": [
{
"matches": ["<all_urls>"],
"js": ["content.js"]
}
],
"icons": {
"16": "images/icon_16.png",
"32": "images/icon_32.png",
"48": "images/icon_48.png",
"128": "images/icon_128.png"
}
}
background.js
chrome.runtime.onInstalled.addListener(() => {
console.log('扩展插件已安装');
});
content.js
console.log('已加载内容脚本！');
document.body.style.backgroundColor = 'yellow';
popup.html
<!DOCTYPE html>
<html>
<head>
<title>Popup</title>
<style>
body {
width: 200px;
height: 100px;
font-family: Arial, sans-serif;
}
</style>
</head>
<body>
<h1>Hello, World!</h1>
<button id="change-color">Change Color</button>
<script src="popup.js"></script>
</body>
</html>
popup.js
document.getElementById('change-color').addEventListener('click', () => {
chrome.tabs.query({ active: true, currentWindow: true }, (tabs) => {
chrome.scripting.executeScript({
target: { tabId: tabs[0].id },
function: () => {
document.body.style.backgroundColor = 'red';
}
});
});
});
3. 配置 manifest.json
manifest.json 文件是 Chrome 插件的配置文件，定义了插件的基本信息、权限和各种元数据。它是插件的核心文件，Chrome 浏览器通过这个文件了解插件的功能和结构。下面是如何配置 manifest.json 文件的详细指南。
manifest.json 文件解释
以下是示例中 manifest.json 文件配置字段，以及每个字段的解释：
| 字段名 | 描述 |
|---|---|
manifest_version | 指定 Manifest 版本，MV3 中该值必须为 3。 |
name | 插件的名称，将显示在 Chrome 插件管理页面和 Chrome 网上应用店中。 |
version | 插件的版本号，使用语义化版本控制（例如：1.0, 1.1.1）。 |
description | 插件的描述，解释插件的功能和用途。 |
action | 配置插件的图标和弹出页面。 - default_popup：定义当用户点击插件图标时显示的 HTML 文件。 |
background | 配置后台脚本，使用 service_worker 字段指定后台脚本文件。- service_worker：指定后台脚本文件，MV3 中改为使用 Service Worker 而不是 Background Page。 |
permissions | 定义插件所需的权限。 - activeTab：允许插件访问当前活动标签页的权限。- scripting：允许插件执行scripting.executeScript() 方法。 |
content_scripts | 定义内容脚本及其注入的页面。 - matches：指定内容脚本将注入哪些页面，这里使用 "<all_urls>" 表示所有页面。- js：指定内容脚本文件。 |
icons | 定义插件的图标文件路径，支持多个尺寸。 |
更多详细字段介绍，请参阅上一篇文章：Chrome 插件 MV3 配置清单
示例说明
上面的示例配置了一个简单的 Chrome 插件，插件会在安装时打印一条消息，并且包含以下功能：
点击插件图标时会弹出 popup.html文件中的内容。后台脚本 background.js会在插件安装时运行。内容脚本 content.js会注入到所有网页中，修改网页背景颜色。插件需要 activeTab和scripting权限。
确保在 manifest.json 文件中正确配置了所有必要的字段，这样才能使插件能够顺利加载并运行。接下来，我们将介绍一下如何编写后台脚本和内容脚本。
4. 后台脚本 (background.js)
后台脚本是 Chrome 插件的核心部分之一，它运行在浏览器的后台，处理长时间运行的任务，如事件监听、消息传递和定时任务。在 Manifest V3 (MV3) 中，后台脚本使用 Service Worker 来代替之前的后台页面，这样可以提高性能和安全性。
后台脚本的作用和功能
后台脚本主要用于以下几种情况：
事件监听：监听和处理各种浏览器事件，如插件安装、标签页更新、消息传递等。 长时间任务：处理需要长时间运行的任务，如周期性检查、数据同步等。 消息传递：与内容脚本和弹出页面进行通信，协调插件的各个部分。
监听插件安装事件
以下是一个简单的后台脚本示例，它会在插件安装时打印一条消息：
// background.js
chrome.runtime.onInstalled.addListener(() => {
console.log('扩展插件已安装！');
});
在这个示例中，我们使用 chrome.runtime.onInstalled.addListener 方法来监听插件安装事件。当插件首次安装或更新时，会触发此事件，并执行回调函数，在控制台打印一条消息。
高级用法示例
除了基本的安装事件监听，后台脚本还可以处理更多的功能。以下是一些高级用法示例：
1. 监听浏览器动作按钮点击事件
// background.js
chrome.action.onClicked.addListener((tab) => {
chrome.scripting.executeScript({
target: { tabId: tab.id },
function: () => {
alert('浏览器的操作按钮被点击了！');
}
});
});
在这个示例中，我们监听浏览器动作按钮（插件图标）点击事件，并在当前标签页中执行一个脚本，弹出一个提示框。
2. 消息传递
后台脚本可以与内容脚本和弹出页面进行消息传递。以下是一个简单的消息传递示例：
后台脚本
// background.js
chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
if (message.action === 'getBackgroundInfo') {
sendResponse({ info: '这是来自 Background 返回的信息' });
}
});
内容脚本
// content.js
chrome.runtime.sendMessage({ action: 'getBackgroundInfo' }, (response) => {
console.log(response.info);
});
在这个示例中，内容脚本向后台脚本发送一条消息，请求获取一些信息，后台脚本接收消息后，返回相关信息。
3. 周期性任务
你可以使用 setInterval 在后台脚本中执行周期性任务，例如每分钟执行一次某个操作：
// background.js
setInterval(() => {
console.log('执行定时任务...');
// 执行周期性任务的逻辑
}, 60000); // 每分钟执行一次
注意事项
在使用后台脚本时，需要注意以下几点：
生命周期：在 MV3 中，后台脚本使用 Service Worker，具有生命周期限制。Service Worker 只会在需要时启动，并在空闲时终止。因此，不能依赖后台脚本保持长时间运行。 权限管理：确保在 manifest.json文件中声明所需的权限，以避免权限不足导致的功能无法正常运行。调试：使用 Chrome 开发者工具调试后台脚本，查看日志和调试信息。
通过利用后台脚本，我们可以实现复杂的插件逻辑和功能。接下来，我们将详细介绍如何编写内容脚本，进一步增强插件的功能。
5. 内容脚本 (content.js)
内容脚本是 Chrome 插件的另一个重要组成部分。它们运行在网页的上下文中，可以直接访问和修改网页的 DOM。内容脚本通常用于实现与网页交互的功能，例如高亮显示文本、修改页面内容或收集页面数据。
内容脚本的作用和功能
内容脚本主要用于以下几种情况：
DOM 操作：修改网页内容，增加、删除或修改 DOM 元素。 与后台脚本通信：发送和接收消息，与后台脚本协同工作。 事件监听：监听用户在网页上的操作，如点击、输入等。
修改网页背景颜色
以下是一个简单的内容脚本示例，它会将当前网页的背景颜色修改为黄色：
// content.js
console.log('已加载内容脚本！');
document.body.style.backgroundColor = 'yellow';
这个脚本在加载时会输出一条日志信息，并将当前网页的背景颜色设置为黄色。接下来，我们需要在 manifest.json 文件中配置这个内容脚本。
高级用法示例
除了简单的 DOM 操作，内容脚本还可以执行更多复杂的任务：
1. 与后台脚本通信
内容脚本可以通过消息传递与后台脚本通信，实现复杂的交互逻辑。
在后台脚本示例中有提到，这里就不重复写了。
2. DOM 操作和事件监听
内容脚本可以操作网页 DOM 并监听用户事件：
// content.js
document.body.style.backgroundColor = 'yellow';
const button = document.createElement('button');
button.textContent = 'Click me';
document.body.appendChild(button);
button.addEventListener('click', () => {
alert('Button clicked!');
});
这个脚本将网页背景颜色设置为黄色，并在页面上添加一个按钮，点击按钮时会弹出提示框。
注意事项
在使用内容脚本时，需要注意以下几点：
隔离性：内容脚本在宿主页面的上下文中运行，但与宿主页面中的 JavaScript 环境是隔离的。你不能直接访问宿主页面的 JavaScript 变量和函数。 权限管理：确保在 manifest.json文件中正确配置内容脚本的权限和匹配模式。性能影响：避免在内容脚本中执行耗时的操作，以免影响网页的性能。
通过使用内容脚本，你可以实现与网页的交互，增强插件的用户体验。在接下来的章节中，我们将继续介绍如何创建和管理插件的popup页面。
6. popup.html 和 popup.js
popup是 Chrome 插件中常见的一部分，通常用于提供用户界面，使用户能够与插件进行交互。当用户点击浏览器工具栏中的插件图标时，插件弹窗会显示出来。
插件弹窗的作用和功能
插件弹窗通常用于以下几种情况：
用户输入：收集用户输入的信息，如表单填写、选项选择等。 展示信息：展示插件运行的结果或状态信息。 触发操作：提供按钮或其他控件，触发插件的功能。
popup.html
首先，我们创建一个 popup.html 文件，定义插件弹窗的结构和样式。
<!-- popup.html -->
<!DOCTYPE html>
<html>
<head>
<title>Popup</title>
<style>
body {
width: 200px;
height: 100px;
font-family: Arial, sans-serif;
}
</style>
</head>
<body>
<h1>Hello, World!</h1>
<button id="change-color">Change Color</button>
<script src="popup.js"></script>
</body>
</html>
在这个示例中，我们定义了一个简单的 HTML 结构，同时通过 <script> 标签引入 popup.js 文件，这个文件将用来处理插件弹窗的交互逻辑。
popup.js
接下来，我们编写 popup.js 文件，处理插件弹窗中的交互逻辑。当用户点击按钮时，我们将改变当前网页的背景颜色。
// popup.js
document.getElementById('change-color').addEventListener('click', () => {
chrome.tabs.query({ active: true, currentWindow: true }, (tabs) => {
chrome.scripting.executeScript({
target: { tabId: tabs[0].id },
function: () => {
document.body.style.backgroundColor = 'red';
}
});
});
});
在这个示例中，我们为按钮添加了一个点击事件监听器。当按钮被点击时，代码将执行以下操作：
使用 chrome.tabs.query获取当前活动的标签页。使用 chrome.scripting.executeScript在当前标签页中执行脚本，将网页背景颜色设置为红色。
高级用法示例
插件弹窗可以实现更复杂的功能，如从存储中读取数据、与后台脚本通信等。以下是一些用法示例：
1. 从存储中读取和显示数据
// popup.js
document.addEventListener('DOMContentLoaded', () => {
chrome.storage.sync.get('color', (data) => {
if (data.color) {
document.body.style.backgroundColor = data.color;
}
});
document.getElementById('change-color').addEventListener('click', () => {
chrome.storage.sync.set({ color: 'red' }, () => {
document.body.style.backgroundColor = 'red';
});
});
});
在这个示例中，插件弹窗加载时会从 Chrome 存储中读取背景颜色，并应用到页面上。点击按钮时，会将背景颜色保存到存储中，并更新页面背景颜色。
2. 与后台脚本通信
// popup.js
document.getElementById('getData').addEventListener('click', () => {
chrome.runtime.sendMessage({ action: 'getData' }, (response) => {
alert('从后台接收数据：' + response.data);
});
});
// background.js
chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
if (message.action === 'getData') {
sendResponse({ data: '我是来自 Background 返回的数据' });
}
});
在这个示例中，插件弹窗发送消息请求数据，后台脚本接收消息并返回数据，然后插件弹窗显示接收到的数据。
注意事项
在开发插件弹窗时，需要注意以下几点：
用户体验：确保插件弹窗的布局和交互逻辑简单明了，提供良好的用户体验。 性能：避免在插件弹窗中执行耗时操作，以免影响用户的交互体验。 安全性：避免在插件弹窗中使用未经验证的用户输入，以防止安全漏洞。
通过合理设计和实现插件弹窗，可以为用户提供直观且便捷的操作界面，增强插件的用户体验。
7. 加载和调试插件
在开发 Chrome 插件时，加载和调试是非常重要的步骤，它们帮助你验证插件的功能并发现潜在的问题。在这一部分，我们将介绍如何在 Chrome 浏览器中加载你的插件，并利用开发者工具进行调试。
加载插件
打开 Chrome 浏览器的扩展程序管理页面
在 Chrome 浏览器中，点击右上角的三点菜单（更多），选择“更多工具” -> “扩展程序”。 或者，直接在地址栏输入 chrome://extensions/并按回车键。
启用开发者模式
在扩展程序管理页面的右上角，找到并启用“开发者模式”开关。这将允许你加载未发布的插件和查看详细的调试信息。
加载插件
此时，你的插件将被加载到 Chrome 浏览器中。你应该能在扩展程序管理页面中看到你的插件图标。
点击“加载已解压的扩展程序”按钮。 选择你创建的插件文件夹 my-chrome-extension，然后点击“选择文件夹”。
更新插件
如果你对插件进行了修改，返回到扩展程序管理页面，点击“刷新”按钮（一个箭头的图标）来更新插件。
调试插件
1. 调试后台脚本
在扩展程序管理页面，点击 背景页链接（通常显示为Service Worker）以打开开发者工具。这将允许你查看和调试后台脚本的日志、错误和其他信息。你可以在 控制台标签页中查看日志消息，使用断点调试代码。
2. 调试内容脚本
内容脚本运行在网页的上下文中，因此需要打开相应的网页来调试它。 在开发者工具中，切换到 源代码标签页，找到内容脚本文件并设置断点。你可以在 控制台标签页中查看内容脚本的日志和错误信息。
3. 调试插件弹窗
点击浏览器工具栏中的插件图标，打开插件弹窗。 在插件弹窗打开的状态下，右键单击插件弹窗并选择 检查打开开发者工具。在开发者工具中，你可以查看和调试插件弹窗的 HTML、CSS 和 JavaScript 文件。
4. 使用 chrome.runtime.lastError
在你的插件代码中，你可以使用 chrome.runtime.lastError来检查 Chrome API 调用中的错误。这对于调试非常有用，例如：
chrome.storage.sync.get('key', (result) => {
if (chrome.runtime.lastError) {
console.error('数据获取异常:', chrome.runtime.lastError);
} else {
console.log('数据获取结果：', result);
}
});
这种方法帮助你捕获并处理 API 调用中的错误，以便更好地理解插件的行为。
8. 插件开发常见问题
在开发和发布 Chrome 插件的过程中，会遇到一些常见的问题，我将一些插件开发常见问题简单汇总罗列如下。
1. 插件无法加载
**检查 manifest.json**：确保manifest.json文件格式正确，没有语法错误。使用 Chrome 的扩展程序管理页面查看错误日志，检查插件加载过程中是否有错误信息。文件路径问题：确保所有引用的文件路径在 manifest.json和代码中都正确无误。
2. 权限问题
权限未授权：确保在 manifest.json文件中声明了插件所需的所有权限。如果插件的功能未按预期工作，检查是否有缺失的权限。权限请求过多：避免请求过多的权限，以免引发用户不信任以及一些插件审核问题。使用最小权限原则，只请求实际需要的权限。
3. 内容脚本不注入
matches配置：检查manifest.json文件中的matches字段，确保配置了正确的 URL 模式。脚本文件路径：确保内容脚本文件路径正确，并且文件存在于指定位置。
4. 插件弹窗功能异常
调试：使用 Chrome 开发者工具调试插件弹窗的 JavaScript 代码，查看控制台中的错误信息。 事件处理：确保插件弹窗中的事件处理逻辑正确，避免由于事件未处理或错误处理导致功能异常。
结语
本篇只是基本的 Chrome 插件开发的教程，通过本文可以完成一些简单的插件开发，下一篇文章我将讲解如何搭建一个 Vue3 的 Chrome 插件开发环境。
相关链接
Chrome 插件 MV3 配置清单：https://mp.weixin.qq.com/s/0_CPLDuvdeLwZo8aD6ygAg Chrome 插件官方文档：https://developer.chrome.com/docs/extensions/get-started/tutorial/hello-world?hl=zh-cn